Release 10.1A: OpenEdge Development:
Progress 4GL Reference

STRING function

Converts a value of any data type into a character value.

Syntax

STRING ( source [ , format ] )

source

An expression of any data type that you want to convert to a character value.

format

The format you want to use for the new character value. This format must be appropriate to the data type of source. If you do not use this argument, Progress uses the EXPORT format for all data types (except DATETIME and DATETIME-TZ, in which case it uses the default display format). This is useful if you want to produce left-justified numbers. See OpenEdge Development: Progress 4GL Handbook for information on data formats.

Example

In the example procedure, the TIME function returns the number of seconds since midnight. The first DISPLAY statement in this procedure uses the STRING function to convert that value into hours and minutes. TIME is the value and “HH:MM AM” is the format used to display the result of the STRING function.

The second DISPLAY statement displays some customer information. It uses the concatenation (+) operator to join together the values of the city, state, and postal-code fields. If these fields were not joined together, the spacing would be different for each customer address depending on the length of the city name.

r-string.p

DISPLAY SKIP(2) "The time is now" STRING(TIME,"HH:MM AM") SKIP(2) WITH NO-BOX NO-LABELS CENTERED. FOR EACH customer: DISPLAY name + " --" + STRING(cust-num, ">>>9") FORMAT "x(30)" AT 1 address AT 33 city + ", " + state + " " + postal-code FORMAT "x(22)" AT 33 SKIP(1) WITH NO-BOX NO-LABELS CENTERED. END.

When you concatenate character fields, Progress creates a new character field, at least for the duration of the procedure. The default display format for character expressions such as that resulting from the concatenation is x(8). This means that Progress allows only 8 spaces for displaying the concatenation of the city, state, and postal-code fields. The FORMAT x(22) option overrides that default x(8) format, telling Progress to set aside 22 spaces for displaying the concatenation of the city, state, and postal-code fields.

Notes

The STRING function is double-byte enabled. The source argument can contain double-byte data.
If source is an integer and format begins HH:MM or HH:MM:SS, STRING formats the source as a time. If the hour is greater than or equal to 12 and there is an A or an a in format, STRING subtracts 12 from the hour and converts the A or the a to a P or p (for A.M. and P.M.). The hour 0 is treated as 12 a.m., and noon is treated as 12 p.m. If you use AM/PM format, HH is replaced by a leading blank and a digit if the hour is between
0 and 9.

If seconds (SS) are not in the format, then the time is truncated to hours and minutes.

If source is a RAW value, you must specify an appropriate format to return the character string representation.
When source is a DATETIME or DATETIME-TZ expression, the STRING function converts the expression to a character value in the specified format. If source is a DATETIME expression, and a time zone offset is present in the format string, the character value contains the time zone offset of the session. If source is a DATETIME-TZ expression, and time zone offset is not present in the format string, the character value contains the local date and time relative to the time zone of the DATETIME-TZ value.
The STRING function converts a DATE, and the date part of a DATETIME or DATETIME-TZ, using the format specified by the DATE-FORMAT attribute or the Date Format (-d) startup parameter.

For more information about the Date Format (-d) startup parameter, see OpenEdge Deployment: Startup Command and Parameter Reference .

You can use the STRING function to convert an object reference for a class object instance to a character value. The STRING function implicitly calls the ToString( ) method of the class to convert the specified object reference.

See also

DECIMAL function, INTEGER function